Objects (IM: XOv)

Inside Macintosh: QuickDraw GX Programmer's Overview / Part 1 - Getting Started With QuickDraw GX: Chapter 3 - Using QuickDraw GX Objects

Objects
This section introduces some of the common elements among all objects. It describes some of the more basic QuickDraw functions you would use in your application, such as creating, copying, cloning, and disposing of shapes and supporting objects. It concludes with a section on how multiple shape objects can share a single supporting object--another way that QuickDraw GX takes advantage of the interrelationships between shapes and its referenced objects.

Creating and Copying Shapes
QuickDraw GX allows you to create shapes in a number of ways, the two most commonly used of which are:

You can call a function that creates the shape and allows you to specify an initial geometry at the same time. These functions include GXNewPoint, GXNewLine, GXNewCurve, GXNewRectangle, GXNewPolygons, GXNewPaths, GXNewText, GXNewGlyphs, GXNewLayout, GXNewBitmap, and GXNewPicture.
You can call the GXNewShape function to create a new shape. You specify the shape type as a parameter to this function. After you create the shape, you call another function to initialize the shape's geometry. The function that you call depends on the shape type; for example: GXSetPoint, GXSetLine, GXSetCurve, GXSetRectangle, GXSetPolygon, GXSetPath, GXSetText, GXSetGlyphs, GXSetLayout, GXSetBitmap, and GXSetPicture. This is the way used by the sample program in Chapter 2.

QuickDraw GX maintains a set of default shape objects to assist in the shape-
creation process. QuickDraw GX maintains one default shape object for every type of shape; that is, there is one default point shape, one default line shape, one default curve shape, and so on.
Every time your application starts using QuickDraw GX, QuickDraw GX creates the initial set of default shape objects, which always have the same properties. Initially, the default shape objects all reference the same style,
ink, and transform objects--called the default style, the default ink, and the default transform.
QuickDraw GX copies the values of all the other properties directly from the default shape into the new shape, including its references to its style, ink, and transform objects. This sharing of supporting objects helps to save memory.
If, however, you want to specify a new default shape with a special geometry or references to other supporting objects, QuickDraw GX provides the GXSetDefaultShape function to allow this. This function lets you establish a different default shape, for which you can also set different property values.
Here's an example of how the GXSetDefaultShape function works: If you always want your new curve shape to have some special geometry (for example, (10.0, 10.0), (20.0, 20.0), (10.0, 20.0)), you can create a curve shape with this new geometry and then use the GXSetDefaultShape function to indicate that QuickDraw GX should use your shape as the default shape when creating curve shapes.
Whenever you create a new shape of any type, QuickDraw GX

allocates memory for a new shape object
copies information from the default shape of the same type into the new shape object (Remember that the current defaults may not be the same as
the initial defaults.)
provides you with a reference to the new shape object.

The new shape object is identical to the default shape of the same shape type with two exceptions:

The owner count of the new shape object is always set to 1.
If you specify a geometry when you create the shape (as you do with functions like GXNewPoint, GXNewCurve, and so on), the geometry of the
new shape is set to the geometry that you specify, rather than to a copy
of the geometry of the default shape.

After you have created shapes, you can create copies of them using the GXCopyToShape function. This function copies the information from one shape into another shape. If you don't specify a new shape to copy the information into, this function creates a new shape for you. The GXCopyToShape function simply copies the values of the properties from one shape into another--including the references to style, ink, and transform objects. As a result, a shape and its copy reference the same supporting objects.

Cloning and Disposing of Shapes
When you call a QuickDraw GX function that changes the number of references to a shape, QuickDraw GX changes the owner count of the shape to reflect the new number of references. For example, when you add a shape with an owner count of 1 to a picture, the picture gets a copy of the shape reference. In this situation, QuickDraw GX increments the owner count of the shape to 2. After you add the shape to the picture, you can dispose of it, and QuickDraw GX decrements the owner count to 1. Since the owner count is not 0, QuickDraw GX does not free the memory used by the shape--which is a good thing, since
the picture still needs it! When you dispose of the picture itself, however, QuickDraw GX automatically disposes of the picture's component shapes. This decrements the shape's owner count to 0 and therefore the memory used by the shape is now freed.
When your application makes a copy of a shape reference into a new variable, QuickDraw GX has no way to know that your application now has two references to the shape. Therefore, if you dispose of either reference, QuickDraw GX frees the memory used by the shape and the other reference now contains invalid information.
To avoid this situation, QuickDraw GX provides the GXCloneShape function. The GXCloneShape function takes a shape object reference as a parameter and returns the reference as the function result. But, more importantly, it also increments the owner count of the referenced shape object. Therefore, when you want to create a copy of a shape reference, you use this line of code:
shapeReferenceCopy = GXCloneShape(shapeReference);
instead of this line of code:
shapeReferenceCopy = shapeReference;
Both of these assignment statements copy the shape reference in the shapeReference variable into the shapeReferenceCopy variable. However,
by using the GXCloneShape function, you also increment the owner count of the referenced shape--giving the shape an owner count of 2. Therefore, when you call
GXDisposeShape(shapeReference);
QuickDraw GX decrements the shape's owner count. The resulting
owner count is 1, so the memory used by the shape is not freed, and the shapeReferenceCopy variable still contains a valid shape reference.
Then, when you call
GXDisposeShape(shapeReferenceCopy);
QuickDraw GX decrements the shape's owner count a second time, which results in an owner count of 0, and therefore QuickDraw GX frees the memory used by the shape.

Creating and Copying Supporting Objects
Supporting objects such as styles, inks, and transforms are objects, just as shape objects are. You can create them, copy them, dispose of them, and clone them, just as you can with shape objects. When you create a supporting object, QuickDraw GX provides you with a reference to the supporting object. You
use this reference when examining or modifying its properties.
To create a new supporting object, you use the GXNewStyle, GXNewInk, or GXNewTransform function. These functions create a copy of the default object for that type of object and return a reference to the new style object as the function result. You cannot change the properties of the default style, ink, and transform object; the objects created by the GXNewStyle (or similar) functions always have the same properties.
(You can, however, change the style, ink, or transform objects referenced by the default shape objects. If you do this, then when you create a new shape, the new shape references the new supporting object rather than the default one.)
You can also create a copy of an existing style, ink, or transform object using the GXCopyToStyle, GXCopyToInk, or GXCopyToTransform functions.

Cloning and Disposing of Supporting Objects
Like shape objects, supporting objects have an owner count property which reflects how many references to it exist. When you create a new supporting object, you typically store a reference to it in one of your application's variables. Therefore, QuickDraw GX always initializes the owner count of a new supporting object to 1.
For example, if you create a style object using the GXNewStyle function:
myStyle = GXNewStyle();
QuickDraw GX sets the owner count of the style to 1. If you then associate the style with a particular shape using the GXSetShapeStyle function:
GXSetShapeStyle(myShape, myStyle);
QuickDraw GX automatically increments the owner count of the style to 2--representing the two references to the shape: one in your variable myStyle and one in the style property of the myShape shape object. If you no longer need the reference in your myStyle variable, you can then dispose of it using the GXDisposeStyle function:
GXDisposeStyle(myStyle);
QuickDraw GX then decrements the owner count of the style, leaving an owner count of 1--representing the reference left in the myShape shape object.
If you then dispose of your shape:
GXDisposeShape(myShape);
QuickDraw GX decrements the owner count of the style again, leaving an owner count of 0. Since there are no remaining references to the style, QuickDraw GX frees the memory used by the style object.
There are circumstances where QuickDraw GX does not maintain the owner count of an object for you. In particular, when your application makes a copy of a supporting object reference into a new variable, QuickDraw GX has no way to know that your application now has two references to that object. Therefore, you might dispose of one of the references and QuickDraw GX would free the memory used by the object, leaving the other reference to contain invalid information.
To avoid this situation, QuickDraw GX provides the GXCloneStyle, GXCloneInk, and GXCloneTransform functions. This function takes a style object reference as a parameter, increments the owner count of the
referenced object, and returns the reference as the function result. As an example, to create a copy of a style object reference, you can use this line
of code:
styleReferenceCopy = GXCloneStyle(styleReference);
Sharing Supporting Objects
One of the ways QuickDraw GX saves memory is by allowing multiple shape objects to share supporting objects. Figure 3-2 shows two geometric shapes--a line shape and a polygon shape--sharing a single style object.
Figure 3-2 Sharing styles

Figure 3-2 shows that the pen width property of the shared style object has a value of 1.0. (Of course, the shared style object has many other properties, but for simplicity only the pen width is showed here.)
When you draw either the line shape or the polygon shape, QuickDraw GX examines the pen width property of the style object and renders the shape with the specified pen width.
If you want to change the pen width for both the line shape and the polygon shape, you must first obtain a reference to the shared style object, which you can do using the GXGetShapeStyle function:
sharedStyle = GXGetShapeStyle(myLineShape);
Then you can alter the pen width property of the shared style object using the GXSetStylePen function:
GXSetStylePen(sharedStyle, ff(10));
The resulting situation is shown in Figure 3-3.
Figure 3-3 Changing a property of a shared style

QuickDraw GX also provides a set of functions that allow you to change a
style property for only one shape. An example of this type of function is the GXSetShapePen function. When you call a function like GXSetShapePen, you provide a reference to a shape object. QuickDraw GX changes the appropriate property of that shape's style object.
However, if that shape is sharing its style object with other shapes, QuickDraw GX makes a copy of the style object and changes only the copy!
For example, if you try to reset the pen width in the previous example back to 1.0 using this function call:
GXSetShapePen(myLineShape, ff(1));
QuickDraw GX examines the owner count of the shape's style object and determines that it is greater than 1, which indicates that the style object is being shared. Therefore, QuickDraw GX makes a copy of the style object, associates the line shape with the copy of the style, and changes the pen width of the copy. Therefore, the call to GXSetShapePen changes only the pen width of the line shape--the polygon shape is unaffected, as shown in Figure 3-4.
Figure 3-4 Another way to change the property of a shared style

The other supporting objects--ink objects and transform objects--work in much the same way.
For more information about QuickDraw GX Objects, see Inside Macintosh: QuickDraw GX Objects.